M3U Playlist Maker – English Documentation

Part 1 – Database, Helpers & RDJDATA Builder

Database connection

The function getPdo() creates a PDO connection to the MySQL database using UTF8MB4 encoding and exception-based error handling. It uses global configuration variables for host, database name, user, password and port.

Cue parser (RadioDJ format)

parseCueTimes($cueString) parses a RadioDJ-style cue string (e.g. sta=0&int=5&out=180) into an associative array with keys like sta, int, out, end, etc. If the string is empty or only &, it returns default values (all zeros).

Energy score

getEnergyScore($track) calculates a 0–10 “energy score” based on BPM and intro/outro length. Higher BPM and shorter intros/outros increase the score. This is later used to sort the playlist into a smoother “energy flow”.

Sweeper ID extraction

extractSweeperId($value) strips a leading & from a sweeper reference and returns an empty string if no sweeper is present.

RDJDATA line builder

buildRDJDataLine($track) builds a #RDJDATA: line containing: track ID, cue points (start, intro, end, outro, hooks, etc.) and an optional sweeper ID. This line is written into the M3U so RadioDJ can read cue data directly from the playlist.

Part 2 – Playlist Generator, M3U Writer & Energy Sorting

BPM preset mode

In preset mode (when bpmmode is not manual), the script:

• Selects one random track per configured BPM range.
• Applies filters: genres, year range, excluded words.
• Ensures only enabled, non-jingle tracks are used.

M3U writing (preset mode)

After selecting tracks, the script writes an M3U file:

• Header: #EXTM3U
• For each track:
  • #EXTINF:duration,Artist - Title
  • File path
  • #RDJDATA: line from buildRDJDataLine()

It logs the filename, track count and total duration, and returns these values.

Manual mode

In manual mode, the script:

• Targets a total duration: hours * 3600 seconds.
• Enforces artist separation (e.g. 30 minutes between songs by the same artist).
• Limits consecutive tracks of the same genre.
• Applies BPM, year, genre and exclusion filters.
• Optionally uses a random seed for reproducible shuffling.

It then tries to fill the target duration as closely as possible, first by adding tracks, then by fine-tuning the remaining seconds with exact or near matches.

Energy-wave sorting

Once the playlist is built, it is sorted using getEnergyScore() into a “wave” pattern: medium-energy tracks near the center, higher/lower energy tracks towards the edges. If two tracks have the same wave value, tie-breaking uses outro length and then intro length to improve transitions.

M3U writing (manual mode)

The final playlist is written to an M3U file in the same format: #EXTM3U, followed by #EXTINF, path and #RDJDATA for each track.

Part 3 – HTML Interface, Form Handling & Filters

Hard reset

If the user submits the form with a reset field, the script redirects to the same URL without query parameters, effectively clearing the form and state.

Folders, log file and M3U list

The script sets up:

• A log file for playlist generation messages.
• An M3U folder for saving playlists.
• A list of existing .m3u files for the remix dropdown.

Genre list

It loads all genres from the genre table and uses them to populate a multi-select list in the UI.

Form handling

On POST, the script:

• Reads the selected BPM mode (manual or preset).
• Defines BPM ranges for presets like slow, medium, fast, slow→fast, fast→slow.
• Reads hours, selected genres, BPM min/max, year min/max, seed and exclusion words.
• Builds a $filters array passed into generatePlaylist().

Part 4 – M3U Remixer & New Playlist Generation

M3U remixer

If the user selects an existing M3U file and enters a new filename:

• The script reads the original M3U and groups each track block (#EXTINF, path, #RDJDATA).
• Shuffles these blocks.
• Writes them to a new M3U file with a fresh #EXTM3U header.
• Redirects with ?done=newfile.m3u to trigger the preview.

New playlist generation

If no M3U is chosen, the script:

• Validates that hours ≥ 1.
• Calls generatePlaylist($hours, $filters, $logMessage).
• Optionally renames the generated file to a custom name.
• Appends the log message to the log file.
• Redirects with ?done=filename.m3u on success, or shows an error on failure.

Preview

When ?done=filename.m3u is present, the script:

• Loads the final M3U file.
• Stores the first 20 lines for a quick preview.
• Stores the full file for potential further use.

Part 5 – UI Form, Remix Section, Preview & Scroll-to-Top

Playlist filter fields

The HTML form includes:

• Hours to generate.
• Optional custom filename.
• BPM mode (manual or presets).
• BPM min/max (for manual mode).
• Random seed.
• Year min/max.
• Exclude words in title.
• Multi-select genre list.

Submitting this form without choosing an existing M3U triggers new playlist generation.

Remix existing M3U

A second fieldset lets the user:

• Select an existing M3U from a dropdown.
• Enter a new filename.
• Click “Remix M3U” to create a shuffled version of that playlist.

Preview and reset

If a playlist was created or remixed, the page shows:

• The name of the created playlist.
• A preview of the first 20 lines.
• A “Refresh / Reset Screen” button that reloads the base URL.

Scroll-to-top button

A small floating button appears when the user scrolls down. It:

• Is styled in bright yellow with smooth transitions.
• Becomes visible after scrolling more than 100px.
• Scrolls smoothly back to the top when clicked.

This completes the full English documentation of your M3U Maker: database, helpers, playlist logic, M3U writing, remixing, UI and preview.